---
title: Zaktualizuj do Astro v4.0
description: Jak zaktualizować projekt do najnowszej wersji Astro (v4.0).
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

Ten przewodnik pomoże Ci zaktualizować projekt z Astro v3 do Astro v4.

Potrzebujesz zaktualizować starszy projekt do v3? Zobacz nasz [starszy przewodnik migracyjny](/pl/guides/upgrade-to/v3/).

Potrzebujesz zobaczyć dokumentacje v3? Odwiedź tę [starszą wersję strony dokumentacji (nieutrzymywany snapshot v3.6)](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/).

## Zaktualizuj Astro

Zaktualizuj wersję Astro i wszystkie oficjalne integracje do najnowszych wersji za pomocą menedżera pakietów.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  # Zaktualizuj Astro i oficjalne integracje razem
  npx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  # Zaktualizuj Astro i oficjalne integracje razem
  pnpm dlx @astrojs/upgrade
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  # Zaktualizuj Astro i oficjalne integracje razem
  yarn dlx @astrojs/upgrade
  ```
  </Fragment>
</PackageManagerTabs>

Możesz również [zaktualizować integracje Astro manualnie](/pl/guides/integrations-guide/#manual-upgrading), jeśli to konieczne, i być może będziesz musiał zaktualizować inne zależności w swoim projekcie.

:::note[Potrzebujesz kontynuować?]
Po zaktualizowaniu Astro do najnowszej wersji, możesz nie musieć wprowadzać żadnych zmian do swojego projektu!

Jednakże, jeśli zauważysz błędy lub nieoczekiwane zachowanie, proszę sprawdź poniżej, co się zmieniło i co może wymagać aktualizacji w Twoim projekcie.
:::

Astro v4.0 zawiera [potencjalne zmiany, które mogą powodować problemy](#zmiany-powodujące-problemy), jak również [usunięcie niektórych wcześniej zdezaktualizowanych funkcji](#poprzednio-niewspierane-teraz-usunięte-funkcje).

Jeśli Twój projekt nie działa zgodnie z oczekiwaniami po aktualizacji do wersji v4.0, sprawdź ten przewodnik, aby uzyskać przegląd wszystkich zmian powodujących problemy i instrukcje dotyczące aktualizacji kodu.

Zobacz [dziennik zmian](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) w celu uzyskania pełnych notatek wydania.

## Usunięto Eksperymentalne Flagi w Astro v4.0

Usuń flagę eksperymentalną `devOverlay` i przenieś konfigurację `i18n` na najwyższy poziom w `astro.config.mjs`:

```js del={5-9} ins={11-14} title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})
```

Konfiguracje, `i18n` i przemianowane `devToolbar`, są teraz dostępne w Astro v4.0.

Przeczytaj więcej o tych dwóch ekscytujących funkcjach, i o wielu innych w tym [wpisie na blogu v4.0](https://astro.build/blog/astro-4/)!

## Uaktualnienia

Jakakolwiek znacząca aktualizacja zależności Astro może wprowadzić istotne zmiany w Twoim projekcie.

### Zaktualizowano: Vite 5.0
W Astro v3.0, Vite 4 był używany jako serwer deweloperski i bundler produkcyjny.

Astro v4.0 aktualizuje z Vite 4 do Vite 5.
#### Co powinienem zrobić?

Jeśli używasz wtyczek, konfiguracji lub API specyficznych dla Vite, sprawdź [przewodnik migracyjny Vite](https://vite.dev/guide/migration) w celu sprawdzenia zmian powodujących problemy i zaktualizuj swój projekt w razie potrzeby. W Astro samym w sobie nie ma zmian powodujących problemy.

### Uaktualnione: jednolite zależności dla remark i rehype

W Astro w wersji 3.x używano jednolitej wersji 10 oraz związanych z nią zgodnych pakietów remark/rehype do przetwarzania Markdown i MDX.

W wersji 4.0 Astro uaktualnia [jednolitą do wersji 11](https://github.com/unifiedjs/unified/releases/tag/11.0.0) oraz inne pakiety remark/rehype do najnowszej wersji.

#### Co powinienem zrobić?

Jeśli korzystałeś z niestandardowych pakietów remark/rehype, zaktualizuj wszystkie z nich do najnowszej wersji za pomocą menedżera pakietów, aby upewnić się, że obsługują one jednolitą w wersji 11. Pakiety, których używasz, można znaleźć w pliku `astro.config.mjs`.

Nie powinno być żadnych istotnych zmian łamiących, jeśli korzystasz z aktywnie aktualizowanych pakietów, ale niektóre pakiety mogą jeszcze nie być kompatybilne z jednolitą w wersji 11.
Przed wdrożeniem sprawdź wizualnie swoje strony Markdown/MDX, aby upewnić się, że Twoja witryna działa zgodnie z zamierzeniami.

## Zmiany powodujące problemy

Następujące zmiany są uważane za zmiany powodujące problemy w Astro. Zmiany powodujące problemy mogą lub nie muszą zapewniać tymczasową kompatybilność wsteczną, a cała dokumentacja jest aktualizowana, aby odnosić się tylko do obecnie obsługiwanego kodu.

Jeśli potrzebujesz odnosić się do dokumentacji dla projektu v3.x, możesz przeglądać ten [(nieutrzymywany) snapshot dokumentacji sprzed wydania v4.0](https://docs-git-v3-docs-unmaintained-astrodotbuild.vercel.app/).

### Zmieniona nazwa: `entrypoint` (API integracji)

W Astro v3.x, właściwość `entryPoint` API integracji `injectRoute`, która określała punkt wejścia, była nazwana `entryPoint`.

Astro v4.0 zmienia nazwę tej właściwości na `entrypoint`, aby była zgodna z innymi API Astro. Właściwość `entryPoint` jest niewspierana, ale nadal będzie działać i wyświetlać ostrzeżenie, które zaleca aktualizację kodu.

#### Co powinienem zrobić?

Jeśli masz integracje, które używają API `injectRoute`, zmień nazwę właściwości `entryPoint` na `entrypoint`. Jeśli jesteś autorem biblioteki i chcesz obsługiwać zarówno Astro 3, jak i 4, możesz określić zarówno `entryPoint`, jak i `entrypoint`, w takim przypadku ostrzeżenie nie zostanie wyświetlone.


```js ins={4} del={3}
injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});
```

### Zmiana: Podpis `app.render` w API Integracji

W Astro v3.0, metoda `app.render()` przyjmuje `routeData` i `locals` jaki osobne, opcionalne argumenty. 

Astro v4.0 zmienia podpis `app.render()`. Te dwie właściwości są teraz dostępne w jednym obiekcie. Zarówno obiekt, jak i te dwie właściwości są nadal opcjonalne.

#### Co powinienem zrobić?

Jeśli utrzymujesz adapter, obecny podpis będzie nadal działać do następnej głównej wersji. Aby przejść do nowego podpisu, przekaż `routeData` i `locals` jako właściwości obiektu zamiast jako wiele niezależnych argumentów.

```diff lang="js"
- app.render(request, routeData, locals)
+ app.render(request, { routeData, locals })
```
### Zmiana: adaptery muszą teraz określić obsługiwane funkcje

W Astro w wersji 3.x nie było wymagane, aby adaptery określały funkcje, które obsługują.

W Astro w wersji 4.0 adaptery muszą przekazywać właściwość `supportedAstroFeatures{}` w celu określenia listy obsługiwanych funkcji. Ta właściwość nie jest już opcjonalna.

#### Co powinienem zrobić?

Autorzy adapterów muszą przekazać opcję `supportedAstroFeatures{}` w celu określenia listy obsługiwanych funkcji.

```js title="my-adapter.mjs" ins={9-11}
export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}
```

### Usunięto: Właściwość path języka Shiki

W Astro w wersji 3.x, język Shiki przekazywany do `markdown.shikiConfig.langs` był automatycznie konwertowany na język kompatybilny z Shikiji. Shikiji to narzędzie wewnętrzne używane przez Astro do podświetlania składni.

Astro w wersji 4.0 usuwa obsługę właściwości `path` języka Shiki, która była myląca w konfiguracji. Została zastąpiona importem, który można przekazać bezpośrednio do `langs`.
#### Co powinienem zrobić?

Plik JSON zawierający definicję języka powinien być importowany i przekazywany jako opcja.

```diff lang="js"
// astro.config.js
+ import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
-       { path: '../../custom.tmLanguage.json' },
+       customLang,
      ],
    },
  },
})
```

## Niewspierane funkcje

Następujące niewspierane funkcje nie są już obsługiwane i nie są już dokumentowane. Proszę zaktualizować swój projekt odpowiednio.

Niektóre zdezaktualizowane funkcje mogą tymczasowo nadal działać, dopóki nie zostaną całkowicie usunięte. Inne mogą nie mieć żadnego efektu lub zgłosić błąd, zachęcając do aktualizacji kodu.

### Niewspierane: `handleForms` dla zdarzeń `submit` w przejściach widoku

W Astro w wersji 3.x projekty korzystające z komponentu `<ViewTransitions />` musiały wyraźnie zdecydować o obsłudze zdarzeń `submit` dla elementów `form`. Było to realizowane poprzez przekazywanie właściwości `handleForms`.

Astro v4.0 handles `submit` events for `form` elements by default when `<ViewTransitions />` are used. The `handleForms` prop has been deprecated and no longer has any effect.
W Astro w wersji 4.0 zdarzenia `submit` dla elementów `form` są obsługiwane domyślnie, gdy używane są `<ViewTransitions />`. Właściwość `handleForms` została zdezaktualizowana i nie ma już żadnego efektu.

#### Co powinienem zrobić?


Usuń właściwość `handleForms` z komponentu `ViewTransitions`. Nie jest już potrzebna.

```astro title="src/pages/index.astro" del="handleForms"
---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>
```


Aby zrezygnować z obsługi zdarzenia `submit`, dodaj atrybut `data-astro-reload` do odpowiednich elementów `form`.

```astro title="src/components/Form.astro" ins="data-astro-reload"
<form action="/contact" data-astro-reload>
  <!-- -->
</form>
```

## Poprzednio niewspierane, teraz usunięte funkcje

Następujące zdezaktualizowane funkcje zostały całkowicie usunięte z bazy kodu i nie mogą już być używane. Niektóre z tych funkcji mogły nadal działać w Twoim projekcie nawet po zdezaktualizowaniu. Inne mogły cicho nie mieć żadnego efektu.

Projekty zawierające teraz usunięte funkcje nie będą w stanie być budowane, i nie będzie już żadnej dokumentacji wsparcia zachęcającej do usunięcia tych funkcji.

### Usunięto: zwracanie prostych obiektów z endpointów

W Astro w wersji 3.x zwracanie prostych obiektów z punktów końcowych było zdezaktualizowane, ale nadal było obsługiwane w celu zachowania kompatybilności z Astro w wersji 2. Dodatkowo dostarczono narzędzie `ResponseWithEncoding`, aby ułatwić migrację.

W Astro w wersji 4.0 usunięto obsługę prostych obiektów i wymaga, aby punkty końcowe zawsze zwracały `Response`. Narzędzie `ResponseWithEncoding` również zostało usunięte na rzecz właściwego typu `Response`.

#### Co powinienem zrobić?

Zaktualizuj endpoint aby zwracał obiekt 'Response' bezpośrednio.

```diff lang="ts"
  export async function GET() {
-   return { body: { "title": "Bob's blog" }};
+   return new Response(JSON.stringify({ "title": "Bob's blog" }));
  }
```

Aby usunąc użycie `ResponseWithEncoding`, przepisz swój kod, aby używał `ArrayBuffer` zamiast:

```diff lang="ts"
  export async function GET() {
    const file = await fs.readFile('./bob.png');
-   return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
+   return new Response(file.buffer);
  }
```

### Usunięto: `build.split` i `build.excludeMiddleware`

W Astro w wersji 3.0 opcje konfiguracyjne `build.split` i `build.excludeMiddleware` zostały zdezaktualizowane i zastąpione [opcjami konfiguracyjnymi adaptera](/pl/reference/adapter-reference/#adapter-features), które wykonują te same zadania.

W Astro w wersji 4.0 te właściwości zostały całkowicie usunięte.

#### Co powinienem zrobić?

Jeśli używasz zdezaktualizowanych `build.split` lub `build.excludeMiddleware`, musisz je teraz usunąć, ponieważ już nie istnieją.

Prosze zobacz przewodnik migracyjny v3, aby [zaktualizować te zdezaktualizowane właściwości middleware](/pl/guides/upgrade-to/v3/#deprecated-buildexcludemiddleware-and-buildsplit) z konfiguracjami adaptera.

### Usunięto: `Astro.request.params`

W Astro v3.0, API `Astro.request.params` przestało być aktualizowane, ale zostało zachowane dla zachowania kompatybilności wstecznej.

W Astro v4.0 usunięto tę opcję całkowicie.

#### Co powinienem zrobić?

Zaktualizuj wszystkie wystąpienia do [`Astro.params`](/pl/reference/api-reference/#params), który jest obsługiwanym zamiennikiem.

```astro del={1} ins={2}
const { id } = Astro.request.params;
const { id } = Astro.params;
```

### Usunięto: `markdown.drafts`

W Astro w wersji 3.0 korzystanie z `markdown.drafts` do kontrolowania budowy projektów roboczych zostało zdezaktualizowane.

W Astro w wersji 4.0 ta opcja została całkowicie usunięta.

#### Co powinienem zrobić?

Jeśli korzystasz z niewspieranej `markdown.drafts`, musisz ją teraz usunąć, ponieważ już nie istnieje.

Aby kontynuować oznaczanie niektórych stron w projekcie jako robocze, [przenieś się do kolekcji treści](/pl/guides/content-collections/) i [ręcznie odfiltruj strony](/pl/guides/content-collections/#filtering-collection-queries) z właściwością frontmatter `draft: true`.

### Usunięto: `getHeaders()`

W Astro w wersji 3.0 eksport `getHeaders()` dla Markdowna został zdezaktualizowany i zastąpiony przez `getHeadings()`.

W Astro w wersji 4.0 ta opcja została całkowicie usunięta.

#### Co powiniem zrobić?

Jeśli korzystasz z zdezaktualizowanej metody `getHeaders()`, musisz ją teraz usunąć, ponieważ nie istnieje już. Zastąp wszystkie wystąpienia metodą `getHeadings()`, która jest obsługiwaną zamienną.
```js del={2} ins={3}
const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();
```

### Usunięto: użycie `rss` w `getStaticPaths()`

W Astro w wersji 3.0, użycie zdezaktualizowanego pomocnika `rss` w `getStaticPaths()` powodowało błąd.

W Astro w wersji 4.0 ten pomocnik został całkowicie usunięty.

#### Co powinienem zrobić?

Jeśli korzystasz z nieobsługiwaniej metody generowania kanałów RSS, musisz teraz użyć [`integracji @astrojs/rss`](/pl/recipes/rss/) dla kompletnego ustawienia RSS.

### Usunięto: małe litery w nazwach metod HTTP

W Astro w wersji 3.0 korzystanie z małych liter w nazwach metod żądań HTTP (`get`, `post`, `put`, `all`, `del`) było zdezaktualizowane.

W Astro w wersji 4.0 usunięto obsługę małych liter całkowicie. Wszystkie metody żądań HTTP muszą teraz być zapisywane z użyciem wielkich liter.

#### Co powinienem zrobić?

Jeśli korzystasz z zdezaktualizowanych nazw z małymi literami, musisz teraz zastąpić je ich odpowiednikami z wielkimi literami.

Proszę zajrzyj do przewodnika migracji v3 [dla wskazówek dotyczących korzystania z metod żądań HTTP z wielkimi literami](/pl/guides/upgrade-to/v3/#changed-http-request-methods-case).

### Usunięto: przekierowania 301 przy braku prefiksu `base`

W Astro w wersji 3.x serwer podglądu Astro zwracał przekierowanie 301 podczas dostępu do zasobów z katalogu publicznego bez ścieżki bazowej.

W Astro w wersji 4.0 zasoby katalogu publicznego, gdy serwer podglądu działa, zwracają status 404 bez prefiksu ścieżki bazowej, zgodnie z zachowaniem serwera deweloperskiego.

#### Co powinienem zrobić?

Podczas korzystania z serwera podglądu Astro, wszystkie importy i adresy URL statycznych zasobów z katalogu publicznego muszą mieć [wartośc bazową](/pl/reference/configuration-reference/#base) dodaną jako prefiks do ścieżki.

Poniższy przykład pokazuje atrybut `src`, który jest wymagany do wyświetlenia obrazu z folderu publicznego, gdy skonfigurowano `base: '/docs'`:

```astro title="src/pages/index.astro" ins="/docs"
// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">
```

### Usunięto: Automatyczna konwersja `astro/client-image`

W Astro w wersji 3.x typ `astro/client-image` (używany dla zdezaktualizowanej integracji obrazu) został usunięty, ale był automatycznie konwertowany na domyślny typ Astro `astro/client`, jeśli został znaleziony w pliku `env.d.ts`.

Astro w wersji 4.0 ignoruje `astro/client-image` i nie będzie już automatycznie aktualizować `env.d.ts` dla Ciebie.

#### Co powinienem zrobić?

Jeśli miałeś skonfigurowane typy dla `@astrojs/image` w `src/env.d.ts` i aktualizacja do wersji v3.0 nie skonwertowała typu automatycznie, ręcznie zamień typ `astro/client-image` na `astro/client`.

```ts title="src/env.d.ts" del={1} ins={2}
  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />
```

## Zasoby społecznościowe

Znasz jakieś dobre źródło zasobów dla Astro v4.0? [Edytuj tę stronę](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v4.mdx) i dodaj poniżej link!

## Znane problemy

Proszę sprawdź [problemy Astro na GitHubie](https://github.com/withastro/astro/issues/) w celu sprawdzenia zgłoszonych problemów lub zgłoszenia nowego problemu.
